Open Food Facts API Documentation

About

As a developer, the Open Food Facts API allows you to get information and contribute to the products database. You can create great apps to help people make better food choices and also provide data to enhance the database. Check out how others are making use of the API at https://world.openfoodfacts.org/discover#reuses

Data Disclaimer

The data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative. Therefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the WRITE API.

Use

You can use the OFF API for production cases, as long as 1 API call equals 1 real scan by a user.

Domains

You can either use the global domain (https://world.openfoodfacts.org) or the local domains (https://fr.openfoodfacts.org, https://en.openfoodfacts.org, …) for your API queries.

Endpoint

The Open Food Facts base endpoint is: https://world.openfoodfacts.org

Version

The current version of the API is 0.

Authentication

READ and SEARCH operations

No authentication is required.

However, you have to add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.

For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com

WRITE operations

No authentication is required for adding new products or adding images.

Basic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.

Parameters * user_id: YourUserID * password: YourPassword

Servers

You can do READ/SEARCH/WRITE operations using the production server. To make tests for WRITE operations, use  https://world.openfoodfacts.net (User:off, Password:off).

Security

Use the SSL version of the API: https://world.openfoodfacts.org

Error Codes

  • Product does not exist - HTTP code 200 + “status_verbose” : “product not found” + “Status” : 0. The request format is correct, but the product code does not exist in the database.
  • Wrong Password - HTTP code 200 + an HTML page with a link to log in. The request format is correct, but basic authentication is missing or the password entered is not correct.
  • Server down - HTTP codes 502/503/500
  • Redirect to another product - HTTP code 301

Disclaimer: The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.

Rate limit

The API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls. 

For more information, see: https://world.openfoodfacts.org/data

Preliminary Considerations

The API development is in progress. This has several implications:

  • Open Food Facts and food products are constantly evolving.
  • Assume that data is less reliable until the product is marked as complete. You might want to filter incomplete products to avoid issues (this is especially relevant for allergens or food intolerances). Let your end users know about this and encourage them to exercise caution. Be upfront about possible risks. You can use the following template to inform your users: The data provided to you by this app are retrieved from the Open Food Facts database. No guarantees can be made for the accuracy, completeness, or reliability of the information provided. The data are provided “as is” and the originating source for the data (Open Food Facts) is not liable for any damages arising out of the use of the data.
  • Join our Slack Channel (https://slack-ssl-openfoodfacts.herokuapp.com) to get help, to share your thoughts, to let us know what you build with the API (contact@openfoodfacts.org or in the #API channel) or if you want to use WRITE operations.
  • You can also join the mailing list to be notified when improvements or changes are made to the API (we send only relevant information and very few e-mails. Don’t worry, you won’t be spammed). To join the mailing list, send an empty e-mail to api-subscribe@openfoodfacts.org to subscribe.

License

  • Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data (https://opendatacommons.org/licenses/odbl/summary/index.html) and CC-BY-SA for the pictures (https://creativecommons.org/licenses/by-sa/4.0/). If you don’t own the data, you bear all the legal consequences.
  • Mention Open Food Facts as the source of the data.
  • Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk).
  • Share any additions under the OdBL with the community.
  • By using any part of the API you have read and understood the license.

API Conventions

  • Fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
  • Fields that end with _datetime are dates in the ISO8601 format: yyyy-mm-ddThh:mn:ssZ
  • Fields that end with _tags are comma-separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)
  • Fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language
  • Fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product

Bugs

Do not hesitate to file a bug if you find an issue in the API or need an improvement. You can fill out the issue report on GitHub:

Downloading Data

It is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot. They are available at:

Exporting Data

  • File Encoding: The file encoding is Unicode UTF-8.
  • CSV API: The character that separates fields is < tab > (tabulation).
  • JSON

API Roadmap

API Redesign: The API is far from perfect. It’s been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.

  • Project API: Additives
  • Project API: States
  • Project API: Statistics
  • Project API: Statistics Entry Dates

Other Projects

  • Open Pet Food Facts
  • Open Beauty Facts
  • Open Products Facts

Read Requests 1

READ requests allow you to retrieve the nutritional data of a product with a barcode.

READ Request Example

GET https://[countrycode].openfoodfacts.org/api/v0/product/[barcode].json

GET https://world.openfoodfacts.org/api/v0/product/737628064502.json

Note: You can find a list of supported parameters and an example of a full JSON response in the Parameters section.

Authentication

No authentication is required for READ operations.

However, you have to add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.

For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com

Reading the nutrition facts of a product  |  GET  

Description

GET requests allow you to make two types of calls: READ and SEARCH. This scenario describes how to make GET READ calls to retrieve the nutritional data of products with a barcode.

GET Read Scenario

Meet Dave. Dave is an active Open Food Facts contributor and a developer who wants to build HealthyFoodChoices, an Android app aimed at concious consumers that buy healthy products.

alt text

HealthyFoodChoices will provide information on healthy foods available in the place where their users live. The users can narrow down the results by applying different filters and save their search criteria so that the app shows them the products that match their preferences next time they use it.

To identify the potential users’ needs, Dave has met with some concious consumers. Anna is one of them. Anna doesn’t drink soda, but her nephew does. He will visit her soon, and she wants to compare the nutrition facts of two cola brands, and its variants (diet, zero, and so on) to decide which one to buy. Dave wants his app to make an API call to provide her with this information. 

Structure of the Call

Authentication and Header

To make the API query that returns the products that might be interesting for Anna, Dave doesn’t need to authenticate. However, he has to add a User-Agent HTTP Header with the name of his app, the version, system and a url (if any), not to be blocked by mistake. 

In this case, that would be: User-Agent: HealthyFoodChoices - Android - Version 1.0

Subdomain

Since Anna lives in NY, Dave wants to define the subdomain for the query as us. The subdomain automatically defines the country code (cc) and language of the interface (lc).  

The country code determines that only the products sold in the US are displayed. The language of the interface for the country code us is English.

In this case:

https://us.openfoodfacts.org

API Version

The current version number of the Open Food Facts API is v0.

https://us.openfoodfacts.org/api/v0

Product Barcode

After the version number, the word “product”, followed by its barcode must be added:

https://us.openfoodfacts.org/api/v0/product/

The app will provide Anna with information about additives, sugars and nutriscore of different types of colas, to help her make her purchase decision.

Anna selects the products she wants to compare in the application (Coca-Cola, Pepsi, Coca-Cola diet, Coca-Cola zero and Pepsi diet). The app retrieves the corresponding barcodes and makes the following calls: 




Robotoff Project 7

About

The Robotoff project is intended to complete missing information of products by prompting users to confirm predictions inferred by Artificial Intelligence algorithms. These algorithms are calculated based on “insights”, which are facts about a product that have been extracted or deduced from the product pictures, ingredients, categories, labels, etc…

The project URL is: https://robotoff.openfoodfacts.org/api/v1/{endpoint}. 

Robotoff can interact with all Open Food Facts products and environments. The server_domain field must be used to specify the product/environment (api.openfoodfacts.org for OFF-prod).

Configuration

To configure this feature in your app follow the steps below:

  1. Fetch a JSON file when opening a product. Example: https://robotoff.openfoodfacts.org/api/v1/questions/3274570800026?lang=en&count=3

    {"questions": [{"barcode": "3274570800026", "type": "add-binary", "value": "Scallop", "question": "Does the product belong to this category?", "insight_id": "5cac03bc-a5a7-4ec2-a548-17fd9319fee7", "insight_type": "category", "source_image_url": "https://static.openfoodfacts.org/images/products/327/457/080/0026/front_en.4.400.jpg"}], "status": "found"}

  2. Display the question and possible answers in the UI.

  3. Send back the proper ping to the Open Food Facts server if the user answers.

    https://github.com/openfoodfacts/robotoff/blob/master/doc/api.md

    http://robotoff.openfoodfacts.org/api/v1/insights/annotate?insight_id=(insight_id)&annotation=(1,0,-1)&update=1

Get a random insight  |  GET  

Description

Fetch a random insight.

Parameters

  • type (string, optional): The type of insight. If not provided, an insight from any type will be returned.

  • country (string, optional): Only return predictions with products from a specific country (ex: en:france)

  • value_tag (string, optional): Filter by value tag, i.e the value that is going to be sent to Open Food Facts.

  • server_domain (string, optional): Server domain. Default to ‘api.openfoodfacts.org’



Get a specific insight  |  GET  

Description

Parameters

  • insight_id: ID of the insight


Get all insights for a specific product  |  GET  

Description

Return all insights associated with a specific product.

Parameters

  • barcode: Product barcode
  • server_domain (string, optional) - server domain. Default to ‘api.openfoodfacts.org’


Get nutrient prediction  |  GET  

Description

Parameters

  • ocr_url (string, required): the url of the OCR JSON

Response

Response 200 (application/json)

{ “nutrients”: { “glucid”: [ { “nutrient”: “glucid”, “raw”: “glucides 53 g”, “unit”: “g”, “value”: “53” } ] } }

Get questions  |  GET  

Description

You can get questions for a given product or get random questions.

Parameters to be used to get questions for a given product

  • barcode: Product barcode
  • lang (string, optional): the language of the question/value. Default: en.
  • count (integer, optional): Number of questions to return. Default: 1.
  • server_domain (string, optional): server domain. Default: ‘api.openfoodfacts.org’

Parameters to be used to get random questions

  • lang (string, optional): the language of the question/value. Default: en.
  • count (integer, optional): Number of questions to return. Default: 1.
  • insight_types (list, optional): comma-separated list, filter by insight types.
  • country (string, optional): filter by country tag.
  • brands (string, optional): filter by brands, comma-separated list of brand tags.
  • value_tag (string, optional): filter by value tag, i.e the value that is going to be sent to Openfoodfacts.
  • server_domain (string, optional): server domain. Default: api.openfoodfacts.org.


Get spelling corrections  |  GET  

Description

Parameters

  • text (string, required) - the ingredient text to spellcheck.

Response

Response 200 (application/json)

{ “corrected”: “farine de blé”, “corrections”: [ { “score”: 0.0009564351, “term_corrections”: [ { “correction”: “farine”, “end_offset”: 6, “original”: “fqrine”, “start_offset”: 0 } ] } ], “text”: “fqrine de blé” }

Submit an annotation  |  POST  

Description

Submit an annotation, given the insight_id. The request type must be application/x-www-form-urlencoded.

Parameters

  • insight_id (string, required): ID of the insight
  • annotation (integer, required): Annotation of the prediction:
    • 1 to accept the prediction
    • 0 to refuse it
    • -1 for “unknown”.
  • update (integer, optional): Send the update to Open Food Facts if update=1. Otherwise, the update won’t be sent. This parameter is useful if the update is performed client-side.


Search Requests 1

Search requests allow you to retrieve the nutritional data of products that comply with your search criteria.

To do so, you combine tags to get custom results. This lets you create thousands of custom APIs for your use case.

Important! The search feature only works on whole words, not parts of words. Your application should not have “search as you type” features that send search queries with parts of words, since this causes performance issues on the Open Food Facts server.

Search URL

The search URL you have to use always starts with:

search_url = “https://world.openfoodfacts.org/cgi/search.pl?

Parameters

You can basically use all the parameters you would use in an advanced search on the site: [https://world.openfoodfacts.org/cgi/search.pl?action=display&sort_by=unique_scans_n&page_size=20&action=display graphical advanced search on the site]

There are three types of parameters you can use to filter the results:

  • Criteria
  • Ingredients
  • Nutriments

Note: You can find a list of supported parameters and an example of a full JSON response in the Parameters section.

Criteria

Every time you use a criterion in your query, you must use the following tags:

  • tagtype_0=categories
  • tag_contains_0=contains
  • tag_0=cereals

Example: https://world.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=cereals

Where tagtype_0 can be one of the following:

  • brands
  • categories
  • packaging
  • labels
  • origins
  • manufacturing_places
  • emb_codes
  • purchase_places
  • stores
  • countries
  • additives
  • allergens
  • traces
  • nutrition_grades
  • states
  • contains
  • does_not_contain

If you want to add more criteria to the query, increase the number of the tag. For example:

  • tagtype_0=categories
  • tag_contains_0=contains
  • tag_0=cereals
  • tagtype_1=label
  • tag_contains_1=contains
  • tag_1=kosher

Ingredients

Use the following parameters to include or exclude products containing any additives or ingredients from palm oil:

  • additives

    • without_additives
    • with_additives
    • indifferent_additives

  • ingredients_from_palm_oil

    • without
    • with
    • indifferent

  • ingredients_that_may_be_from_palm_oil

    • without
    • with
    • indifferent

  • ingredients_from_or_that_may_be_from_palm_oil

    • without
    • with
    • indifferent

Nutriments

You can also filter by nutriments (fat, sugars, energy, etc). To do so, you need to add three different parameters for each nutriment:

Example:

  • nutriment_0=energy
  • nutriment_compare_0=lt
  • nutriment_value_0=500

You can enter the following categories (nutriment_0): https://static.openfoodfacts.org/data/taxonomies/nutrients.json

Comparison of nutrients

Nutriment to compare

nutriment_compare_0

Operator

  • lt # less than
  • lte # less than or equal
  • gt # greater than
  • gte # greater than or equal
  • eq # equal to
  • nutriment_value_0 - Value to compare the nutrients to

Other search parameters: Output

  • sort_by # sort by
  • unique_scans_n # Popularity
  • product_name # Product name
  • created_t # Add date
  • last_modified_t # Edit date

Results per page

page_size # page_size

  • 20 # 20
  • 50 # 50
  • 100 # 100
  • 250 # 250
  • 500 # 500
  • 1000 # 1000

Pagination * page=1

Format * json=true (recommended) * xml=true

Linked Data

Whenever possible, Open Food Facts entities are linked to Wikidata, and in turn to Wikipedia. What this means is that you get access to a trove of additional encyclopedic knowledge about food. You can for instance get: Wikipedia articles about Camembert, the translation of salt in many languages, the molecular structure of a cosmetic ingredient… We provide the Wikidata QID, which is an unambiguous, stable and reliable identifier for a concept that will be useful to actually retrieve info from Wikipedia and Wikidata.

Example

https://world.openfoodfacts.org/categories.json

{"linkeddata":{"wikidata:en":"Q40050"},"url":"https://world.openfoodfacts.org/category/beverages","name":"Beverages","id":"en:beverages","products":14196}
Beverages >> https://world.openfoodfacts.org/category/beverages >> Q40050 >> https://www.wikidata.org/wiki/Q40050

Retrieving info from Wikipedia and Wikidata

You can use the Wikipedia and Wikidata APIs to get the information you want

Examples of Things you Can Do

  • Provide more context and more information about a specific product, a category of products, a quality label, a geography, a brand, a packaging material, an ingredient…
  • Perform checks or computations by mixing Wikidata information and Open Food Facts information (and possibly other APIs)

Searching for products  |  GET   https://us.openfoodfacts.org/cgi/search.pl

Description

GET requests allow you to make two types of calls: READ and SEARCH. This scenario describes how to make a GET SEARCH call to retrieve the nutritional data of products that comply with your search criteria.

GET Search Scenario

Meet Dave. Dave is an Open Food Facts contributor and a developer. He wants to  build HealthyFoodChoices, an Android app aimed at concious consumers that buy local and healthy products.

alt text

HealthyFoodChoices will provide information on healthy foods by country. The users can narrow down the results by applying different filters and save their search criteria so that the app shows them the products that match their preferences next time they use it.

To identify the potential users’ needs, Dave has met with some concious consumers. Anna is one of them. This 36-year old New Yorker follows a plant-based diet and wants to avoid the intake of palm oil. She wants to find a breakfast cereal brand that does not use palm oil or additives and has a good nutriscore (A).

Structure of the Call

Authentication and Header

To make the API query that returns the products that might be interesting for Anna, Dave doesn’t need to authenticate. However, he has to add a User-Agent HTTP Header with the name of his app, the version, system and a url (if any), not to be blocked by mistake. 

In this case, that would be: User-Agent: HealthyFoodChoices - Android - Version 1.0

Subdomain

Since Anna lives in NY, Dave wants to define the subdomain for the query as us. The subdomain automatically defines the country code (cc) and language of the interface (lc).

The country code determines that only the products sold in the US are displayed. The language of the interface for the country code US is English.

In this case:

https://us.openfoodfacts.org

Query Parameters

Dave wants to fine-tune the query to provide Anna with the products that match her buying preferences. To do so, he wants to drill down the results to display only breakfast cereals.

First, he adds the following sequence after the https call: /cgi/search.pl? (all search queries need to include this)

Then, he defines some tags and the apropriate values: action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals

where:

  • action introduces the action to be performed (process)
  • tagtype_0 adds the first search criterion (categories)
  • tag_contains_0=contains determines that the results should be included (note that you can exclude products from the search)
  • tag_0 defines the category to be filtered by (breakfast_cereals)

Note: The parameters are concatenated with &

To retrieve breakfast cereals sold in the US, Dave makes the following call: https://us.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals

With this query, the nutrition facts of more than 200 products are displayed.

Then, Dave wants to exclude the products that contain ingredients from palm oil. He adds a new parameter to the query: 

  • ingredients_from_palm_oil=without

This parameter excludes the products that might contain palm oil ingredients from the search.

https://us.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals&ingredients_from_palm_oil=without

Next, Dave adds another parameter to exclude the products that contain additives:

  • additives=without

The query is as follows:

https://us.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals&ingredients_from_palm_oil=without&additives=without

Finally, Dave adds another parameter to include only products with a nutriscore A. The nutriscore is a nutrition grade determined by the amount of healthy and unhealthy nutrients.

  • tagtype_1=nutrition_grade
  • tag_contains_1=contains
  • tag_1=A

The complete query looks like this:

https://us.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals&tagtype_1=nutrition_grades&tag_contains_1=contains&tag_1=A&additives=without&ingredients_from_palm_oil=without

Add the json=true parameter to avoid scraping.

https://us.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=breakfast_cereals&tagtype_1=nutrition_grades&tag_contains_1=contains&tag_1=A&additives=without&ingredients_from_palm_oil=without&json=true

Anna can see now at a glance which products match her search criteria. In this case, around 20 brands of breakfast cereals.

Query
KeyValueDescription
actionprocess
tagtype_0categories
tag_contains_0contains
tag_0breakfast_cereals
tagtype_1nutrition_grades
tag_contains_1contains
tag_1A
additiveswithout
ingredients_from_palm_oilwithout

Taxonomies 12

List of Additive Classes  |  GET  

Description

You can use the following query to retrieve the Nova Groups taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/additives_classes.json



List of Additives  |  GET  

Description

You can use the following query to retrieve the additives taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/additives.json

Use the following query to retrieve the additives facet:

GET http://world.openfoodfacts.org/additives.json

The response includes the code and name of the additive, a link to a Wikipedia page with more information about the additive, and the number of products containing this additive in the Open Food Facts database.

You can drill-down to the list of products containing a certain additive by making the following call:

GET https://world.openfoodfacts.org/additive/additivecode-additivename.json

Example:

GET https://world.openfoodfacts.org/additive/e322-lecithins.json



List of Allergens  |  GET  

Description

You can use the following query to retrieve the allergens taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/allergens.json

Use the following query to retrieve the allergens facet:

GET https://world.openfoodfacts.org/allergens.json



List of Brands  |  GET  

Description

You can use the following query to retrieve the brands taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/brands.json

Use the following query to retrieve the brands facet:

GET https://world.openfoodfacts.org/brands.json



List of Countries  |  GET  

Description

You can use the following query to retrieve the countries taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/countries.json

Use the following query to retrieve the countries facet:

GET https://world.openfoodfacts.org/countries.json



List of Ingredient Analysis  |  GET  

Description

This taxonomy/facet includes the presence, absence or unawareness of the presence of:

  • palm oil: Palm oil free, Palm oil, Palm oil content unknown, may-contain-palm-oil
  • vegetarian ingredients: vegetarian, non-vegetarian, vegetarian-status-unknown, maybe-vegetarian.
  • vegan ingredients: vegan, non-vegan, vegan-status-unknown, maybe-vegan.

You can use the following query to retrieve the ingredient analysis taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/ingredients-analysis.json

Use the following query to retrieve the ingredient analysis facet:

GET http://world.openfoodfacts.org/ingredients-analysis.json

Important! Parsing might not be perfect and the ingredient detection might have issues in some languages. For more information on how the translation works, see: https://github.com/openfoodfacts/openfoodfacts-server/blob/master/taxonomies/ingredients.txt


List of Ingredients  |  GET  

Description

You can use the following query to retrieve the ingredients taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/ingredients.json

Use the following query to retrieve the ingredients facet:

GET http://world.openfoodfacts.org/ingredients.json

Note: An example of the ingredients facet has not been added to this request because the response is too long.


List of Languages  |  GET  

Description

You can use the following query to retrieve the languages taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/languages.json

Use the following query to retrieve the languages facet:

GET https://world.openfoodfacts.org/languages.json



List of Nova Groups  |  GET  

Description

You can use the following query to retrieve the Nova Groups taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/nova_groups.json



List of Nutrient Levels  |  GET  

Description

The nutrient levels indicate the quantity of fat, saturated fat, sugar and salt in a product.

The quantity levels are the following:

  • low
  • moderate
  • high

For more information about the quantity levels, read the annex 3 of the guide on the development of front of pack nutrition labels, issued by the Department of Health of the British Government, the Food Standards Agency, and devolved administrations in Scotland, Northern Ireland and Wales in collaboration with the British Retail Consortium. Annex 3. Determining red, amber and green colour coding (and High, Medium and Low (HML) text if applied): https://www.food.gov.uk/sites/default/files/media/document/fop-guidance_0.pdf

Examples:

  • Saturated fat in moderate quantity
  • Salt in high quantity

You can use the following query to retrieve the nutrient levels taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/nutrient_levels.json



List of States  |  GET  

Description

You can use the following query to retrieve the states taxonomy:

GET https://world.openfoodfacts.org/data/taxonomies/states.json

Use the following query to retrieve the states facet:

GET https://world.openfoodfacts.org/states.json

You can drill-down to the list of products in a certain state by making the following call:

GET https://world.openfoodfacts.org/state/statename.json

Example:

To retrieve a list of products with photo, you can make the following request:

GET https://world.openfoodfacts.org/state/photos-uploaded.json



Taxonomies, Facets and Categories  |  GET  

Description

Taxonomies, Facets and Categories

Taxonomies

A taxonomy is a regulated syntax definition for a property; for example, allergens. The definition includes all possible entries and translations into other languages (synonyms). Taxonomies are global and multilingual and do not vary by country.

The taxonomy file is static, it is created when a new taxonomy is built, it is stable and validated by the OFF team.

Taxonomies are not considered API calls, since they are static files.

https://world.openfoodfacts.org/data/taxonomies/allergens.json

The product’s category parents are indicated in the first line of the taxonomy:

 en:chocolate-advent-calendars: {
 parents: [
 "en:advent-calendars",
 "en:christmas-chocolates"
 ],

Facets

A facet refers to all the values that contributors add to a property. A facet includes the values defined in the taxonomy and the new values added by the contributors. Facet change constantly and their values are not validated. Facets vary by country.

Facet queries can be made to retrieve a list of the values that belong to a specific facet (for example, labels) and its product count.

A facet query has the following structure:

https://world.openfoodfacts.org/allergens.json

You can replace world with any of the country codes described in the Countries taxonomy.

The values of the facet that are not included in the taxonomy are marked with an asterisk (*).

See an example here: https://us.openfoodfacts.org/labels

Categories

A category is a “tag” used to classify foods in different groups. For example, cheeses. Categories can be freely entered by users. Food category is one of the facets of Open Food Facts. Other examples are allergens or additives.

Note that there is also a taxonomy of categories used to define as many as possible of the “tags” entered by users as known entries in the taxonomy.

The following query retrieves a list of all categories available:

https://world.openfoodfacts.org/categories.json

You can retrieve a list of products that belong to a specific category. For example, “cheeses”:

https://world.openfoodfacts.org/category/cheeses.json

Note that the query has an additional parameter “category”.

Important! The categories hierarchy is not a tree but a lattice: each node can have several children, but also several parents.


Write Requests 4

POST calls allow you to add new products and data to the Open Food Facts database.

Test Calls

https://world.openfoodfacts.net is the server you can use for making test calls (User:off, Password:off). Remember to join the API channel on Slack before making a POST request!

Structure of the Call

Authentication and Header

No authentication is required for adding new products or adding images, although it is recommended.

Basic authentication is required for editing existing products. You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.

Parameters * user_id: YourUserID. * password: YourPassword

Product Barcode

After the version number, the word “code”, followed by its barcode must be added:

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004

Posting Additional Values for a Field (new product)

You can add several values to a field by adding a comma between them.

Example:

labels = “labelA, labelB”

Reading back, use labels_tags to get an array of labels.

Adding Additional Information to Existing Fields (existing product)

To add additional information to existing parameters, add the prefix add_ to the parameter name.

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004&user_id=myappname&password=******&add_categories=Desserts

Example:

https://world.openfoodfacts.org/cgi/product_jqm2.pl?code=0048151623426&user_id=usernameexample&password=*****&product_name=Maryland%20Choc%20Chip&quantity=230g&brands=Golden%20Cookies&nutriment_energy=450&nutriment_energy_unit=kJ&nutrition_data_per=serving&ingredients_text=Fortified%20wheat%20flour%2C%20Chocolate%20chips%20%2825%25%29%2C%20Sugar%2C%20Palm%20oil%2C%20Golden%20syrup%2C%20Whey%20and%20whey%20derivatives%20%28Milk%29%2C%20Raising%20agents%2C%20Salt%2C%20Flavouring&traces=Milk%2C+Soya%2C+Nuts%2C+Wheat

Note: Use %20 for spaces (e.g. Maryland%20Choc%20Chip), & to concatenate parameters (e.g. quantity=230g&brands=Golden%20Cookies) and = to link the parameter to the value (e.g. nutriment_energy=450).

Breakdown: * Server url + barcode: https://world.openfoodfacts.org/cgi/product_jqm2.pl?code=0048151623426 * User id: usernameexample * __Password__:password * __Product name__:product_name=Maryland%20Choc%20Chip. __Important:__ German umlauts are not converted (e.g. ä -> ae). For more information, see the __FAQ__ section. * __Quantity__:quantity=230g * __Brands__:brands=Golden%20Cookies * __Energy__:nutriment_energy=450 * __Nutrition data per__:nutrition_data_per=serving * __Ingredients__:Fortified%20wheat%20flour%2C%20Chocolate%20chips%20%2825%25%29%2C%20Sugar%2C%20Palm%20oil%2C%20Golden%20syrup%2C%20Whey%20and%20whey%20derivatives%20%28Milk%29%2C%20Raising%20agents%2C%20Salt%2C%20Flavouring&traces=Milk%2C+Soya%2C+Nuts%2C+Wheat`

Other Parameters:

  • Nutriment_energy_unit: possible values are: kj, kcal. This value always applies to the nutriment_energy value. The normalized energy value, in kJ, can be found in energy_100g.

Note: You can find a list of supported parameters and an example of a full JSON response in the Parameters section.

Status Codes

  • Valid edits get the following response: { ... "status_verbose": "fields saved", "status": 1 ... }
  • If the password entered is not correct, an HTML 200 code + an HTML page with a link to login is displayed.
  • If the code is not correct, you get a 0 response.

About Copyright

Make sure you don’t upload photos or information with copyright. Everything you send is OdBL for the data, and CC-BY-SA for the pictures. Be aware that you bear the legal consequences for uploading protected content.

Adding products  |  POST  

Description

WRITE Scenario - Adding New products

Meet Dave. He is a developer and an active Open Food Facts contributor that regularly adds new products to the database and completes missing information via API calls. He has described the process below to show other developers how easy it is to contribute.

Structure of the Call

Authentication and Header

If you have an app that makes POST calls and you don’t want your users to authenticate in Open Food Facts, you can create a global account. Dave has created a global account for the app he is developing with the following credentials:

  • user_id: myappname
  • password: 123456

Subdomain

Dave wants to define the subdomain for the query as us. The subdomain automatically defines the country code (cc) and language of the interface (lc).  

The country code determines that only the products sold in the US are displayed. The language of the interface for the country code US is English.

In this case:

https://us.openfoodfacts.org/cgi/product_jqm2.pl?​​​​​​​

Product Barcode

After the version number, the word code, followed by its barcode must be added:

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004

Credentials

Dave adds his user credentials to the call as follows:

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004&user_id=myappname&password=******

Add & to concatenate the parameters.

Parameters

You can define one or more parameters to add, for example, the brand and the Kosher label:

  • brands: Häagen-Dazs
  • labels: kosher

The call looks like this:

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004&user_id=myappname&password=******&brands=Häagen-Dazs&labels=kosher

Adding a Comment to your WRITE request.

Use the comment parameter to add the id of the user editing the product. The id should not contain any personal data.

Important! The user id is not the identifier of an Open Food facts user, but the id generated by your system.

It should be structured as: user-agent + user-id.

Example

comment=Edit by a Healthy Choices 1.2 iOS user - SxGFRZkFwdytsK2NYaDg4MzRVenNvUEI4LzU2a2JWK05LZkFRSWc9PQ

Adding Additional Information to Existing Fields

To add additional information to existing parameters, add the prefix add_ to the parameter name.

Important! If you don’t use the add_ prefix, the existing values will be deleted.

Example

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004&user_id=myappname&password=******&add_categories=Desserts

To see the complete list of parameters, see the Parameters section.


Photos - Performing OCR  |  POST   https://world.openfoodfacts.net/cgi/ingredients.pl

Description

Open Food Facts uses optical character recognition (OCR) to retrieve nutritional data and other information from the product labels.

Process

  1. Capture the barcode of the product where you want to perform the OCR.
  2. The Product Opener server software opens the image (process_image=1)
  3. Product Opener returns a JSON response. Processing is done using Tesseract or Google Cloud Vision (recommended). The result is often cripped with errors with Tesseract, less with Google Cloud Vision.

Notes: * The OCR may contain errors. Encourage your users to correct the output using the ingredients WRITE API. * You can also use your own OCR, especially if to plan to send a high number of queries.

OCR with Google Cloud Vision

We recommend Google’s Vision API to detect and extract text from the images. For more information about this product, see: https://cloud.google.com/vision/docs/ocr?hl=en

Parameters



Query
KeyValueDescription
code13333560
idingredients_en
process_image1
ocr_enginetesseract

Photos - Selecting, Cropping, Rotating  |  POST   https://world.openfoodfacts.org/cgi/product_image_crop.pl

Description

Selecting, cropping and rotating photos are non-destructive actions. That means, the original version of the image uploaded to the system is kept as is. The subsequent changes made to the image are also stored as versions of the original image.

The actions described in this topic do not modify the image, but provide metadata on how to use it (the data of the corners in the case of selection and the data of the rotation). That is, you send an image to the API, provide an id, you define, for example, the cropping and rotation parameters and as a response, the server generates a new image as requested and you can call this new version of the image.

Selecting and Cropping Photos

Note: Cropping is only relevant for editing existing products. You cannot crop an image the first time you upload it to the system.

Parameters

To select and crop photos, you need to define: * a barcode * an incremental id (Similar to a version) * cropping parameters (x1, y1, x2, y2) * (optional) additional operations: - angle= Angle of the rotation

Example:

POST https://world.openfoodfacts.org/cgi/product_image_crop.pl?code=3266110700910&id=nutrition_fr&imgid=1&angle=90

Test server

https://world.openfoodfacts.net/cgi/product_image_crop.org

Rotating Photos

Although we recommend rotating photos manually and uploading a new version of the image, the OFF API allows you make api calls to automate this process.

You can rotate existing photos by 90º, 180º or 270º clockwise.

Parameters

  • imgid
  • id = language version. Example: nutrition_fr
  • code = barcode
  • angle = angle of rotation. Possible values: 90º, 180º, 270º.

Example:

POST https://world.openfoodfacts.org/cgi/product_image_crop.pl?code=3266110700910&id=nutrition_fr&imgid=1&angle=90

Deselecting Photos

You have to deselect photos to remove languages that are not relevant to the product.

Query
KeyValueDescription
code3266110700910
idnutrition_fr
imgid1
angle90

Photos - Uploading  |  POST   https://us.openfoodfacts.org/cgi/product_jqm2.pl

Description

Uploading Photos

Photos are source and proof of data. Read this topic to learn how to make calls to upload them to the database.

When you upload an image to Open Food Facts, the image is stored as is.

The first photo uploaded is autoselected as “front” photo.

Read the following before uploading photos:

  • Image Quality: Uploading quality photos of a product, its ingredients and nutrition table is very important, since it allows the Open Food Facts OCR system to retrieve important data to analyze the product. The minimal allowed size for photos is 640 x 160 px.

  • Upload Behavior: In case you upload more than one photo of the front, the ingredients and the nutrition facts, beware that only the first photo of each category will be displayed. (You might want to take additional images of labels, recycling instructions, and so on). All photos will be saved.

  • Label Languages: Multilingual products have several photos based on languages present on the packaging. You can specify the language by adding a lang code suffix to the request.

POST Photo Requests

The API requests to upload photos is very straightforward. Just add the product code followed by product_image_upload and one of the parameters as follows:

Product Barcode

To define the product barcode, add the word code to the call, followed by its barcode:

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004

Image Upload

Then, add the parameter product_image_upload.pl to the call and specify from which perspective the photo was taken:

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004&product_image_upload.pl/imgupload_front=cheeriosfrontphoto.jpg

Parameters

  • code: the barcode of the product
  • imagefield: (can be either: front | ingredients | nutrition)
  • imgupload_front : your image file if imagefield=front
  • imgupload_ingredients: your image file if imagefield=ingredients
  • imgupload_nutrition: your image file if imagefield=nutrition


Query
KeyValueDescription
code0074570036004
product_image_upload.pl/imgupload_frontcheeriosfrontphoto.jpg